package com.maiko.maikoaiagent.agent;

import lombok.Data;
import lombok.EqualsAndHashCode;

/**
 * ReActAgent 是一个实现 ReAct 模式（Reasoning and Acting）的智能代理抽象类。
 * 它继承自 BaseAgent，实现了“思考（Think）- 行动（Act）”的执行循环。
 * <p>
 * ReAct 模式由 Google 提出，是一种适合 Agent 应用场景的架构，
 * 支持代理根据当前环境思考（Reasoning），并据此做出行动（Acting）。
 * <p>
 * 子类需实现 think() 和 act() 两个核心方法，以自定义具体的推理逻辑与行为执行。
 * <p>
 * 典型应用场景包括：
 * - 智能问答系统（需要外部检索 + 推理）
 * - 自动任务分解与执行
 * - 多步决策系统（如 AgentHub, LangGraph 等）
 *
 * @author: Maiko7
 * @create: 2025-07-10 7:52
 */

@EqualsAndHashCode(callSuper = true) // 保证继承 BaseAgent 的 equals/hashCode 正确重写
@Data
public abstract class ReActAgent extends BaseAgent {

    /**
     * 智能体进行“思考”步骤，分析当前上下文、历史消息、任务目标等。
     *
     * @return true 表示思考结果需要行动（如调用工具、外部搜索），false 表示无需行动（可结束）。
     */
    public abstract boolean think();

    /**
     * 智能体根据思考结果进行“行动”。
     * 子类可在此方法中实现调用工具、发出请求、执行指令等操作。
     *
     * @return 行动执行的文字描述结果，可用于日志或输出展示。
     */
    public abstract String act();

    /**
     * 步骤执行逻辑，遵循 ReAct 模式的核心流程：
     * 1. 先进行思考（think）
     * 2. 若需要行动，则执行行动（act）
     *
     * @return 当前步骤的执行结果文本
     */
    @Override
    public String step() {
        try {
            // 判断是否需要行动
            boolean shouldAct = think();
            if (!shouldAct) {
                return "思考完成 - 无需行动";
            }
            // 执行行动逻辑
            return act();
        } catch (Exception e) {
            // 异常处理
            e.printStackTrace();
            return "步骤执行失败: " + e.getMessage();
        }
    }
}


